.TH std::experimental::filesystem::rename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::experimental::filesystem::rename \- std::experimental::filesystem::rename

.SH Synopsis
   Defined in header <experimental/filesystem>
   void rename( const path& old_p, const path& new_p );
   void rename( const path& old_p, const path& new_p, std::error_code&  (filesystem TS)
   ec );

   Moves or renames the filesystem object identified by old_p to new_p as if by the
   POSIX rename:

     * If old_p is a non-directory file, then new_p must be one of:

     * the same file as old_p or a hardlink to it: nothing is done in this case.
     * existing non-directory file: new_p is first deleted, then, without allowing
       other processes to observe new_p as deleted, the pathname new_p is linked to the
       file and old_p is unlinked from the file. Write permissions are required to both
       the directory that contains old_p and the directory that contains new_p.
     * non-existing file in an existing directory: The pathname new_p is linked to the
       file and old_p is unlinked from the file. Write permissions are required to both
       the directory that contains old_p and the directory that contains new_p.
     * If old_p is a directory, then new_p must be one of:

     * the same directory as old_p or a hardlink to it: nothing is done in this case.
     * existing directory: new_p is deleted if empty on POSIX systems, but this may be
       an error on other systems. If not an error, then new_p is first deleted, then,
       without allowing other processes to observe new_p as deleted, the pathname new_p
       is linked to the directory and old_p is unlinked from the directory. Write
       permissions are required to both the directory that contains old_p and the
       directory that contains new_p.
     * non-existing directory, not ending with a directory separator, and whose parent
       directory exists: The pathname new_p is linked to the directory and old_p is
       unlinked from the directory. Write permissions are required to both the
       directory that contains old_p and the directory that contains new_p.
     * Symlinks are not followed: if old_p is a symlink, it is itself renamed, not its
       target. If new_p is an existing symlink, it is itself erased, not its target.

   Rename fails if

     * new_p ends with dot or with dot-dot.
     * new_p names a non-existing directory ending with a directory separator.
     * old_p is a directory which is an ancestor of new_p.

.SH Parameters

   old_p - path to move or rename
   new_p - target path for the move/rename operation
   ec    - out-parameter for error reporting in the non-throwing overload

.SH Return value

   \fI(none)\fP

.SH Exceptions

   The overload that does not take an error_code& parameter throws filesystem_error on
   underlying OS API errors, constructed with old_p as the first argument, new_p as the
   second argument, and the OS error code as the error code argument. std::bad_alloc
   may be thrown if memory allocation fails. The overload taking an error_code&
   parameter sets it to the OS API error code if an OS API call fails, and executes
   ec.clear() if no errors occur. This overload has
   noexcept specification:
   noexcept


.SH Example


// Run this code

 #include <experimental/filesystem>
 #include <fstream>
 #include <iostream>
 namespace fs = std::experimental::filesystem;

 int main()
 {
     fs::path p = fs::current_path() / "sandbox";
     fs::create_directories(p/"from");
     std::ofstream(p/"from/file1.txt").put('a');
     fs::create_directory(p/"to");

 //  fs::rename(p/"from/file1.txt", p/"to/"); // error: to is a directory
     fs::rename(p/"from/file1.txt", p/"to/file2.txt"); // OK
 //  fs::rename(p/"from", p/"to"); // error: to is not empty
     fs::rename(p/"from", p/"to/subdir"); // OK

     fs::remove_all(p);
 }

.SH See also

   rename     renames a file
              \fI(function)\fP
   remove     removes a file or empty directory
   remove_all removes a file or directory and all its contents, recursively
              \fI(function)\fP

.SH Categories:
     * Noindexed pages
     * unconditionally noexcept
.SH Hidden categories:
     * Pages with unreviewed unconditional noexcept template
     * Pages with unreviewed noexcept template
